Let’s read Julia documentation in your preferred language

SatoshiTerasaki@AtelierArith

Overview

  • Introduction to DocstringTranslation.jl
  • Multilingual translation of Julia documentation
  • Running demonstration

Background and Challenges

  • Julia’s official documentation is exclusively written in English
  • All up-to-date information is provided only in English
  • For non-English-speaking developers, reading and participating in discussions in English represents significant psychological and time costs
  • The translation process itself is time-consuming

Solution: Developing an automated translation system utilizing machine translation - DocstringTranslation.jl 😎

What is DocstringTranslation.jl?

A package for translating Julia docstrings into any preferred language

@doc exp (Original)

julia> @doc exp
  exp(x)

  Compute the natural base exponential of x, in other words ^x.

  See also exp2, exp10, and cis.

  Examples
  ≡≡≡≡≡≡≡≡

  julia> exp(1.0)
  2.718281828459045

  julia> exp(im * pi)  cis(pi)
  true

  exp(A::AbstractMatrix)

  Compute the matrix exponential of A, defined as:

  e^A = \sum_{n=0}^{\infty} \frac{A^n}{n!}.

  For symmetric or Hermitian matrices A, an eigendecomposition (eigen) is used; otherwise, the scaling and squaring algorithm
  (see [^H05]) is employed.

  │ [^H05]

  │  Nicholas J. Higham, "The squaring and scaling method for the matrix exponential revisited", SIAM Journal
  │  on Matrix Analysis and Applications, 26(4), 2005, 1179-1193. doi:10.1137/090768539
  │  (https://doi.org/10.1137/090768539)

  Examples
  ≡≡≡≡≡≡≡≡

  julia> A = Matrix(1.0I, 2, 2)
  2×2 Matrix{Float64}:
   1.0  0.0
   0.0  1.0

  julia> exp(A)
  2×2 Matrix{Float64}:
   2.71828  0.0
   0.0      2.71828

@doc exp (Translated into Japanese)

julia> ENV["OPENAI_API_KEY"] = "sk-<blah>"
julia> using DocstringTranslation
julia> @switchlang! :ja
julia> @doc exp
  exp(x)

  Compute the natural base exponential of x, in other words ^x.

  Also see exp2, exp10, and cis.

  Examples
  ≡≡

  julia> exp(1.0)
  2.718281828459045

  julia> exp(im * pi)  cis(pi)
  true

  exp(A::AbstractMatrix)

  Compute the matrix exponential of matrix A, defined as:

  e^A = \sum_{n=0}^{\infty} \frac{A^n}{n!}.

  For symmetric or Hermitian matrices A, an eigendecomposition (eigen) is used; otherwise, the scaling and squaring algorithm
  (see [^H05]) is employed.

  │ [^H05]

  │  Nicholas J. Higham, "The squaring and scaling method for the matrix exponential revisited", SIAM Journal
  │  on Matrix Analysis and Applications, 26(4), 2005, 1179-1193. doi:10.1137/090768539
  │  (https://doi.org/10.1137/090768539)

  Examples
  ≡≡

  julia> A = Matrix(1.0I, 2, 2)
  2×2 Matrix{Float64}:
   1.0  0.0
   0.0  1.0

  julia> exp(A)
  2×2 Matrix{Float64}:
   2.71828  0.0
   0.0      2.71828

What is DocstringTranslation.jl?

How Translation Works

  • @switchlang! :ja overrides the Docs.parsedoc(d::DocStr) method.
# Rough implementation outline
@eval function Docs.parsedoc(d::DocStr)
    if d.object === nothing
        md = Docs.formatdoc(d)
        md.meta[:module] = d.data[:module]
        md.meta[:path] = d.data[:path]
        begin # workaround
          translated_md = translate_docstring_with_openai(md)
        end # workaround
        d.object = translated_md
    end
    d.object
end

For more details, refer to the actual implementation.

Docstrings on IJulia.jl

We can view translated docstrings in Jupyter

Live Docs on Pluto.jl

We can view translated docstrings in Pluto

Translation of Documenter.jl-based documentation

--- a/docs/make.jl
+++ b/docs/make.jl
@@ -4,6 +4,10 @@ using DocumenterCitations
 # `using SpecialFunctions` for all doctests
 DocMeta.setdocmeta!(SpecialFunctions, :DocTestSetup, :(using SpecialFunctions); recursive=true)

+using DocstringTranslation
+@switchlang! :ja
+DocstringTranslation.switchtargetpackage!(SpecialFunctions)
+
 bib = CitationBibliography(
        joinpath(@__DIR__, "src", "refs.bi
b");
        style = :authoryear,

Translation of Documenter.jl-based documentation

Translation Results for Julia’s Official Documentation

Multilingual Julia Documentation:

About Result Caching

  • Uses Scratch.jl to store translation results locally
  • Prevents repeated API calls each time the REPL starts
  • Allows modification of translation results by editing <lang>.md files (e.g., ja.md)
  • Enables sharing of translation results among users
$ tree ~/.julia/scratchspaces/d404e13b-1f8e-41a5-a26a-0b758a0c6c97/translation
├── Base
│   └── 1.11
│       └── Math
│           └── 77be4ada26c623c913ebbdae5d8450a4dfe8f3cbf67837faac9d7193342d2bfe
│               ├── ja.md
│               └── original.md
└── LinearAlgebra
    └── 1.11
        └── 46c0494a8a2adffc6f71752b60448da1743997b5b1791b71e3830113e9b9cc46
            ├── ja.md
            └── original.md

8 directories, 4 files

Additional Information

  • DocstringTranslationOllamaBackend.jl (Ollama backend)

Demo

Let’s see the translation functionality in action!

Summary

  • Enables multilingual support for Julia documentation
  • Supports both docstrings and Documenter.jl
  • Improves efficiency through result caching
  • Supports multiple translation backends

Future Plans: - Enhance translation quality - Add support for more languages - Facilitate community sharing of translation results

Thank You

Repositories: